ASA DataFest 2024 Workshop

Module 03: Modern Presentation with Quarto

Iris Jiang & Thomas Fung

School of Mathematical and Physical Sciences

Acknowledgement

Introducing Quarto

Motivating Video

What is Quarto?

  • Quarto is the next generation of R Markdown for publishing, including dynamic and static documents and multi-lingual programming language support.
  • Quarto unifies and extends the R Markdown ecosystem
    • unifies for people who love R Markdown
    • extends for people who don’t know R Markdown
  • Quarto version 1.0 only released July 2022!

Artwork by @allison_horst

Let’s talk about Markdown first

We need to start with markup

  • A markup (language) is a system for annotating a document in a way that is visually distinguishable from the content.
  • It is used only to format the text, so that when the document is processed, the markup language does not appear.
    • The term markup is partly evolved from how editors were communicating changes on a manuscripts.

Now we move to markdown

  • There are many markup language on the market
    • html
    • Markdown
    • LaTeX
  • Markdown is a lightwieght markup language that you have to use code to add formatting elements to your content.
  • Portable, platform independent, and widely used.

How does Quarto work?

Artwork by @allison_horst

Let’s compare a .qmd file with its html output

YAML

  • Stands for YAML Ain’t Markup Language
    • Previously stands for Yet Another Markup Language
  • Appears at the top of your document.
  • YAML is commonly used for configuration files, and starts and ends with ---
  • Within the YAML, you can change
    • Author and document information
    • Document type so you can use a single one markdown file to generate many different formats

Let’s talk more about Quarto

Why the name “Quarto”?

  • Quarto had meaning in the history of publishing, which is the format of a book or pamphlet produced from full sheets printed with eight pages of text, four to a side, then folded twice to produce four leaves.

Why Quarto?

Quarto makes moving between formats straightforward.

Why Quarto? (Cont.)

Quarto enables collaborating across coding languages.

Why Quarto? (Cont.)

Quarto flattens the learning curve.

Artwork by @allison_horst

Getting started!

  • Quarto is bundled and comes pre-installed with RStudio v2022.07.1 and beyond!

Creating an Quarto Document in R Studio

  • File \(\rightarrow\) New File \(\rightarrow\) Quarto Document;

  • or

Creating an Quarto Document in R Studio (cont.)

  • Choose appropriate options.
    • You may want to use the visual markdown editor as your default editor.
  • Both .rmd and .qmd are just a plain text file.

Your mission, should you choose to accept it!

  • Create two Quarto/QMD documents (from the template), one is output as html and the other one as pdf.
  • Compare them and see whether you can notice the difference between them.
  • Try to render them and observe the output.

Important

  • In order to produce pdf documents, you need to install the \(\LaTeX\) typesetting system.
  • The simplest way is to install via the TinyTeX package.
pak::pak("tinytex") # uncomment to install the package or
# install.packages("tinytex")
tinytex::install_tinytex()

03:00

YAML

  • You should be able to see YAML appears at the top of your document.
  • Within the YAML, you can change
    • Author and document information
    • Document type so you can use a single one .qmd file to generate many different formats
      • html
      • pdf
  • Some common document types that can be generated from R Markdown and Quarto can be found on the next tab.
Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides
Advanced Layout
Cross References
Websites & Blogs
Books
Interactivity
Paged HTML
  • Planned
Journal Articles
Dashboards
  • Planned
Interactive Tutorials
  • No equivalent planned

YAML (cont.)

  • Notice that Quarto can autofill/auto-complete options in your YAML.
    • Press Ctrl + space to list all available YAML options.
    • Press Tab key to auto-complete.

Markdown Basics

Basic Syntax – Text Formatting

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax.

**bold text**

*italicized text*

***bold and italicized text***

bold text

italicized text

bold and italicized text

`code`

code

> Blockquote

Blockquote

Basic Syntax – Lists

1. First item 
2. Second item 
3. Third item 
  1. First item
  2. Second item
  3. Third item
- First item
- Second item
- Third item
  • First item
  • Second item
  • Third item
- First item
  - Second item
    - Third item
  • First item
    • Second item
      • Third item

Basic Syntax – Equations

inline math: $E = mc^{2}$

display math:

$$E = mc^{2}$$

inline math: \(E = mc^{2}\)

display math:

\[E = mc^{2}\]

Tip

R Inline code

  • Uses a single pair of back ticks and “r”. E.g.
`r 2 + 2 `
  • Back ticks are the key in the top left corner of a standard US qwerty keyboard.
  • When compiled, the inline command is sent to R for computation.
  • The command is then removed from the source document and replaced by the R output.
    • Inline command does not echo and always evaluates (explain more on the next few slides).

R code chunk

  • We use code chunk for more complex and larger computation.
```{r cars}
#| include: true
#| echo: false
library(tidyverse)
mtcars %>% 
  filter(cyl == 6)
```
  • They are fenced by ```.
    • r: language engine
    • cars: unique chunk name
  • You can add customisable options in after {r} brackets i.e. after the chunk name
  • You can add chunk options with hashpipe #|:
    • include: include chunk output or not
    • echo: display source code or not

R code chunk (Cont.)

  • You can use a shortcut for inserting an R code chunk:
    • Within an .qmd, press
      • Mac: Cmd + Opt + i
      • PC: Ctrl + Alt + i
```{r} 
```
  • You can then put any R code in it.
```{r cars}
#| message: false
library(tidyverse)
mtcars %>% 
  filter(cyl == 6)
```
  • cars: unique chunk name

  • message: suppress message or not. If you don’t suppress them:

R code chunk (Cont.)

  • If the message option is set to “true”
library(tidyverse)
── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.1.4     ✔ readr     2.1.4
✔ forcats   1.0.0     ✔ stringr   1.5.1
✔ ggplot2   3.4.4     ✔ tibble    3.2.1
✔ lubridate 1.9.3     ✔ tidyr     1.3.1
✔ purrr     1.0.2     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

Tip

There are many more options chunk options available so feel free to explore more in order to customise your work https://quarto.org/docs/computations/execution-options.html.

Hashpipe (#|)

  • Quarto introduces the concept/notation of #| (read the hashpipe).

  • Hashpipe enables a more readable way to organise your chunk options.

```{r scatterplot}
#| fig-align: "center"
#| fig-width: 4.5 
#| fig-height: 4
plot(speed ~ dist, cars)
```

Tip

  • If you can’t remember all the options, please remember that you can auto-complete them!

Visual Editor

Quarto - Visual Editor

Format

Insert

Table

Insert Anything trick

  • You can also use the catch-all shortcut Cmd + / for Mac or Ctrl + / for Windows within visual editor mode to insert just about anything.
    • If you are at the beginning of a line you can also enter plain / to invoke the shortcut.
  • Just execute the shortcut then type what you want to insert (or you can just scroll to find what you need)

Getting started with Quarto Presentation

Creating a Quarto Presentation in R Studio

  • File \(\rightarrow\) New File \(\rightarrow\) Quarto Presentation

  • Quarto supports a variety of formats for creating presentations:

    • revealjs – reveal.js (HTML)
    • pptx – PowerPoinst (MS Office)
    • beamer – Beamer (LaTeX/PDF)

Creating a Quarto Presentation in R Studio (Cont.)

  • Choose appropriate options (in this case we will choose Presentation).
    • You may want to use the visual markdown editor as your default editor.

Shared syntax across all formats

  • Incremental reveal/list
  • Multiple columns for layout
  • Title/subtitle/author etc
  • Headings
  • Code/Output

Creating slides

  • Slides are delineated using headings. For example, here is a simple slide show with two slides each defined with a level 2 heading (##).
---
title: "Habits"
author: "John Doe"
format: revealjs
---

## Getting up

- Turn off alarm
- Get out of bed

## Going to sleep

- Get in bed
- Count sheep

Incremental Lists

  • Controllable via YAML:
---
format: 
  revealjs:
    incremental: true
---

Or turn on/off via fenced divs:

::: {.incremental}
- List element A
- List element B
:::
::: {.nonincremental}
- List element A
- List element B
:::

Multicolumn Columns

  • For example the two column layout:
:::: {.columns}

::: {.column width='40%'}
Left column
:::

::: {.column width='60%'}
Right column
:::
::::

and get output:

Left column

Right column

Addins: Quartostamp

  • It’s hard to memorise and typed in all these different divs into your Quarto presentations.
  • Introducing quartostamp, an R package containing an RStudio Addin to insert pre-written divs and classes for you.
  • To install the package:

pak::pak("matt-dray/quartostamp")
# or alternatively:
# install.packages("remotes")
# remotes::install_github("matt-dray/quartostamp")

Addins: Quartostamp (cont.)

  • To use:
    • Put the cursor in your Quarto file where you’d like to insert an element.
    • Click the ‘RStudio Addins’ dropdown at the top of the RStudio IDE
    • Scroll/search for ‘QUARTOSTAMP’ and click the function you want.
    • The various Callout Blocks are highly recommended. You should try them out!

Your mission, should you choose to accept it!

  • Create a quarto presentation using the template in a format of your choice.
    • We recommend you to give all three formats a try to see which one you like.
  • Add a new slide.
  • Add some code chunks into your presentation and then render it.
  • Use quartostamp addin to add different elements and customise your slide deck.
    • Use a two column layout
    • Use one of the callout block.

Quarto for the Python user

How does it work?

Creating a quarto presentation in VS Code

  • You can also author quarto document with other tools such as
    • JupyterLab
    • VS Code (or VS Code Studio)
    • Neovim
    • or just any Text Editor
  • Here we will use VS Code Studio to demonstrate.
    • Why? It also offers a visual editor just like RStudio to give you a word-processor style interface.
  • After installing Quarto, you also need to install the Quarto extension from the VS Code Extension Marketplace

Creating a quarto presentation in VS Code (Cont.)

  • This is what it looks like if you open a .qmd file:

Creating a quarto presentation in VS Code (Cont.)

  • You can also just create a new .qmd file within VS Code
  • Notice that the default output format for a quarto presentation is revealjs.

Creating a quarto presentation in VS Code (Cont.)

  • To render your document, you can then either

    • use the drop down menu near the top right hand corner 👉
    • use a keyboard shortcut: Ctrl+Shift+K for Windows or Cmd+Shift+K for Mac.
    • modify and then type the following command in the Terminal
    quarto preview /your_path/your_quarto.qmd

Creating a quarto presentation in VS Code (Cont.)

Visual Editor in VS Code

VS Code Error

ModuleNotFoundError: No module named 'nbformat'
  • Enter the following in the qmd file and run them in VS Code
```{python}
import sys
print(sys.executable)
```

which gives

/usr/local/bin/python3.11

Now that I knew which Python was being used, I could install the nbformat (or any other packages that were missing) in the Terminal with

/usr/local/bin/python3.11 -m pip install nbformat 

We hope…

Thanks!